SetTranslationAdvertisement

SetTranslationAdvertisement
Header:	TranslationExtensions.h		Carbon status:	Supported

Allows your translation extension to install an advertisement into the upper portion of the progress dialog box.

OSErr SetTranslationAdvertisement (
    TranslationRefNum refNum, 
    PicHandle advertisement
);

refNum

A translation reference number. You should set this parameter to the translation reference number passed to your DoTranslateFileProcPtr or DoTranslateScrapProcPtr callback functions. The Translation Manager uses that number internally.

advertisement

A handle to a picture to display in the upper portion of the dialog box. If this parameter is NULL, no advertisement is displayed and the upper portion of the dialog box is removed before the box is displayed to the user. After the function installs the specified advertisement, it then displays the dialog box.

Your translation extension can read the picture data from its resource fork, but it should detach the resource from the resource fork (by calling the DetachResource function) and make the handle unpurgeable before calling this function. Because you’ll usually load the picture data into the temporary heap provided for the translation extension, the picture data is automatically disposed of when that heap is destroyed. If your translation extension loads the picture data elsewhere in memory, you are responsible for disposing of it before returning from your DoTranslateFile or DoTranslateScrap callback function.

The size of the picture to display can be no larger than 280 by 50 pixels. If the picture you specify is smaller than that, it is automatically centered (both vertically and horizontally) in the available space.

function result: A result code.

DISCUSSION

Your translation extension should call this function only in response to the kTranslateTranslateFile or kTranslateTranslateScrap request code (that is, you should only call this function in your DoTranslateFile or DoTranslateScrap callback function). Do not call this function in response to any other request code or from any code that isn’t a translation extension.

You must call this function before you call the UpdateTranslationProgress function for the first time.

SPECIAL CONSIDERATIONS

This function might cause memory to be moved or purged; you should not call it at interrupt time.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when Translation 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by Translation 1.0 and later.